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6. REMOTE JOB ENTRY (RJE) USER’S GUIDE 
INTRODUCTION 


A set of background processes support remote job entry (RJE) from a UNIX operating system to IBM Sys- 
tem/360 and /370 host machines (computers). RJE is the communal name for this subsystem. 


The UNIX operating system communicates with the IBM Job Entry Subsystem by mimicking an IBM 360 
remote multileaving work station. The UNIX System Administrator’s Manual under rje(8) summarizes its de- 
sign and operating procedures. The UNIX System User’s Manual also contains a description of the send(1C) 
command, which is the primary user method of submitting jobs to the RJE facilities. (In this document, RJE 
refers to the facilities provided by the UNIX operating system and not to the Remote Job Entry facilities of 
the IBM HASP or JES2 subsystems). The rjestat(1C) command allows the user to monitor the status of RJE 
and to send operator commands to the host machine. 


Throughout this section, each reference of the form name(1M), name(7), or name(8) refers to entries in 
the UNIX System Administrator's Manual. All other references to entries of the form name(N), where “N” 
is a number (1 through 6) possibly followed by a letter, refer to entry name in section N of the UNIX System 
User’s Manual. 


This guide is a tutorial overview of RJE and is addressed to the user who needs to know how to use the RJE 
facilities but does not need to know details of its implementation. The two following parts constitute a general 
introduction to the RJE facilities. A sample JES2 output listing can be found in Table 6.A. 


GENERAL 


The user should have access to a copy of the UNIX System User’s Manual. This manual contains a descrip- 
tion of the system and includes a section How to Get Started, which introduces the user to UNIX operating sys- 
tem; the user should be familiar with the contents of that section before proceeding with this document. 


In order to begin using the RJE facilities, the user need only become familiar with a subset of basic com- 
mands. The user must understand the directory structure of the file system and should know something about 
the attributes of files: see ed(1), chmod(1), chown(1), ep(1), In(1), 1s(1), mkdir(1), mv(1), rm(1). The user 
must know how to enter, examine, edit, and print out text files: see cat(1), ed(1), pr(1). The user should also 
know how to communicate with other users and with the system: see mail(1), mesg(1), who(1), write(1). And, 
finally, the user might have to know how to describe the user terminal to the system: see ascii(5), stty(1), and 
tabs(1). 


BASIC RJE 
A. Submitting Jobs 


Assume that the user has used the standard text editor, ed(1), to create a file, jobfile, that contains the 
user’s job control statements (JCL) and input data. This file should look exactly like a card deck except that 
alphabetic characters, for convenience, may be in either uppercase or lowercase. Below is an example: 


$ cat jobfile 
//gener job (9999,r740),pgmrname,class=x usr=(mylogin,myplace) 
//step exec pgm=iebgener 
//sysprint dd sysout=a 
//sysin dd dummy 
//sysut2 dd sysout=a 
//sysutl dd * 
first card of input data 
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last card of input data 
/* (comment card) 


To submit the job jobfile for execution, the user must invoke the send(1) command: 
$ send jobfile 
The system will reply: 


10 cards 
Queued as /usr/rje/rd3125 


Note that send tells how many cards it submitted and reports the position that the job jobfile has been 
assigned in the queue of all jobs waiting to be transmitted to the host machine system. Until the transmission 
of the job actually begins, the user can prevent the job from being transmitted by doing a chmod 0 on the 
queued file to make it unreadable. For the above example, transmission could be stopped by entering: 


chmod 0 /usr/rje/rd3125 . 
B. Job Messages 


Two job messages, a job acknowledgment message (not returned by all host machines) and a job ready mes- 
sage, will be returned with the job from the host machine. Two bells, with an interval of one second between 
the bells, precede each message. The bells should be interpreted by the user as a warning to stop typing on the 
terminal, so that the imminent message will not be interspersed with the typing input of the user. 


When the job jobfile is accepted by the host machine, a job number will be assigned to it; and a job acknowl- 
edgment message will be generated for this event. This indicates that the job jobfile has been scheduled on the 
host machine. Later, after the job has executed, the job output file can be directed to the UNIX operating system, 
and a job ready message is returned for this event. The job output file can also be redirected to another device 
(card punch, etc.) on the host machine. The user will be notified automatically for both of the events. If the user 
is logged in when RJE detects these events and is permitting messages to be sent to the terminal [see mesg(1)], 
the following two messages will be sent (still using the example above): 


Job Acknowledgment Message 


Two bells $12:18:42 gener job 384 — — rd3125 acknowledged 
Job Ready Message 
Two bells 
12:21:54 gener job 384 — — /al/user/rje/prnt0 ready 


If the user is not logged in when one of these events occurs or does not allow messages to be sent to the termi- 
nal, then the notification will be posted to the user via the mail(1) command. The user can prevent messages 
directly by executing the mesg(1) command or indirectly by executing another command, such as pr(1), which 
prohibits messages for as long as it is active. The user may inspect (by invoking the mail command) the mail 
file (/usr/mail/logname) at any time for messages that have been diverted. Setting the user MAIL variable to 
the name of the user mail file will cause the shell to notify the user when mail arrives. For this example, the 
mail notice might be as follows: 


$ mail 
From rje Mon Aug 1 12:20:36 1981 
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$12:18:42 gener job 384 — — rd3125 acknowledged 
2d 

From rje Mon Aug 1 12:21:55 1981 

12:21:54 gener job 384 — — /al/user/rje/prnt0 ready 
?d 


The job acknowledgment message performs two functions. First, the message confirms the fact that the job 
has been scheduled for execution. Second, the message assigns a number to the job in such a way that the num- 
ber and the name together will uniquely identify the job for a period of time on the host machine. 


The output ready message provides the name of a UNIX file (prnt0) into which output has been written and 
identifies the job to which the output belongs [see Is(1)]: 


$ ls —1 prnt0 
=r xr — 1 rye 1184 Aug 1 12:21 prnt0 


Note that “rje” retains ownership of the output file and allows only the user to have read access to it (no group 
id name is listed). The user should inspect the file, perhaps extract some information from it, and then promptly 
delete the file thus [see rm(1)]: 


$ rm —f prnt0 
C. Output File Retention 


The retention of machine-generated files, such as RJE output files, is discouraged. It is the responsibility 
of the user to remove files from the RJE directory to conserve memory space. The RJE output files may be trun- 
cated if the output file exceeds a set limit. This limit is tunable by the system administrator. The part of the 
output file that goes beyond the currently set limit will be discarded, with no provision for retrieval. If the out- 
put file is truncated, a warning message will appear in the truncated output file as follows: 


Two bells 
12:21:54 gener job 384 — — /al/user/rje/prnt0 ready (truncated) 


The user should also be aware that RJE attempts to keep a set number of blocks free on any file system it uses. 
This number is also tunable by the system administrator. Warning messages or suspension of certain functions 
will occur as this limit is approached. 


D. Examining Output Files 


The most elementary way to examine the output file is to cat the file to the user terminal. The appendix 
illustrates the result of listing the output file of our sample job in this way. Because the UNIX operating system 
does not have high volume printing capability, any large listings should be routed to the host machine. 


The structure of an output file (listing) will generally conform to the following sequence: 


HASP log 

jel information 
data sets 
HASP end 


Normally “burst” pages will not be present. Single, double, and triple spacing is reflected in the output file, 
but other “forms” controls, such as the skip to the top of a new page, are suppressed. Page boundaries are indi- 
cated’ by the presence of a blank (space character) at the end of the last line of each page. 


The big file scanner bfs(1) or the standard text editor ed(1) provides a more flexible method than cat(1) 
for examining printed output; bfs can handle files of any size and is more efficient than ed for scanning files. 
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The RJE facility is also capable of receiving punched card output data as formatted files [see pnceh(4)]; this 
format allows an exact representation ofan arbitrary card deck to be stored in the UNIX operating system. 
However, there are few commands that can be used to manipulate these files. The user should route or redirect 
the punched output file to one of the host machine output devices. 


SEND COMMAND 


The send(1C) command is capable of invoking more general processing than has been indicated previously 
in Basic RJE. The send command will concatenate a sequence of files to create a single job stream. This allows 
files of JCL and files of data to be maintained separately in the UNIX operating system. In addition, it recog- 
nizes any line of an input file that begins with the character ‘~’ as being a control line that can call for the 
inclusion, inside the current file, of some other file. This allows the user to send a top level skeleton file that 
“pulls” or calls in subordinate files as needed. Some of these may be “virtual” files that actually consist of the 
output of UNIX commands or shell procedures. Furthermore, the send command is able to collect input data 
directly from a terminal and can be instructed to prompt the terminal user for the required data. 


Each source of input can contain a format specification that determines such things as how to expand tabs 
and how long can an input line be. File specification fspee(4) explains how to define such formats. When prop- 
erly instructed, send will also replace arbitrarily defined keywords by other text strings or by Extended Binary 
Coded Decimal Interchange Code (EBCDIC) character codes. (These two substitution facilities are useful in 
other applications besides RJE; for that reason, the send command may be invoked under the name gath(1C) 
to produce the standard output without submitting an RJE job). 


Two options of the send command that all users should be acquainted with are—first, the ability to specify 
to which host machine a job is to be submitted and, second, a flag that guarantees that a job will be transmitted 
to the host machine in the order of submission (relative to other jobs submitted with the same flag). To execute 
the above sample job on a host machine cited to RJE as A, issue the command: 


$ send A jobfile 


When a host machine is not explicitly cited, send makes a reasonable choice. 
To ensure that a job will be transmitted in the order of submission, set the —x flags of send by entering: 
$ send A —x jobfile 


This flag should be used sparingly. The complete list of arguments and flags that control the execution of send 
are defined under the send(1C) command. 


JOB STREAM 


It is assumed that the job stream submitted as the result of a single execution of send consists of a single 
“Sob”, i.e., the file that is queued for transmission should contain one JOB card near the beginning and no other 
job cards. A priority control card may legitimately precede the JOB card. The JOB card must conform to the 
standards of the host machine. A typical JOB card has the following format: 


JOB Card Format 


//name job (acct[, . . .J), pgmrname[,keywds="] [usr=. . .] 


USER FIELD SPECIFICATION 


A. Options & 


The user field “usr=...” (specified on the job card, comment card, or input data card) is required for any 
print or punch output file that is to be returned to the UNIX operating system user. The format of this field 
is: 


usr=(login,place,[level]) 
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where login is the UNIX login name of the user, level is the desired level of notification, and the place value 
is defined in cases A through E below: 


A. If place is the name of a directory (writable by others), then the output file is placed there as a unique 
ra prnt or pnch file. The permission mode of the file will be 454. 


B. If place is the name of an existing, writable (by others), nonexecutable (by others) file, then the output 
file replaces it. The permission mode of the file will be 454. 


C. If place is the name of a nonexistent file in a writable (by others) directory, then the output file is placed 
there. The permission mode of the file will be 454. / 


D. If place is the name of an executable (by others) file, then the RJE output is set up as standard input 
to place and place is executed. Five string arguments are passed to place. For example, if place is a shell 
€ procedure, the following arguments are passed as $1... $5: 


tT Flag indicating whether file space is scarce in the file system where place resides. 
A O indicates that space is not scarce; 1 indicates space is scarce. 


2: Job name. 
3. Name of programmer. 
4, Job number. 
5. Login name from the “usr=...” field specifications. 
& A “:” is passed if a value is not present. The current directory for the execution of place will be set to 
the directory containing place. The environment [see environ(5)] will contain values for LOGNAME 


and HOME based on the login name from the “usr=...” specification and a value for TZ (time zone). 
Since the login name supplied in the “usr=...” field specification cannot be believed for security pur- 
poses, the UID will be set to a reserved value. 


E. In all other cases, the output will be discarded. 


The place value must not be a full pathname, unless it refers to an executable file (refer to case D above). 
For cases A, B, and C above (and case D, if a full pathname is not supplied), the name of the login directory 
of the user will be used to form a full pathname. 


The “usr=...” field specification may occur anywhere within the first 100 card images sent and within the 
& first 200 output images received by the UNIX operating system. The only restriction is that it be contained com- 
pletely on a single line or card image. Therefore, the “usr=...” field may be placed on a JOB card or comment 

card. The field may also be passed as data on an input data card. 


If the output files are to be redirected from the host machine to another UNIX system machine, a “usr= 
...” specification field card, if not already present, must be supplied by the user. This can be done by placing 
a job step that creates this card before the output steps. The remote UNIX system machine will handle the out- 
put files as specified on the “usr=...” specification field card. 
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B. RJE Message Level of Notification 


Messages generated by RJE or returned from the host machine are assigned a level of importance ranging 
from 1 to 9. The levels in use are: 


3 transmittal assurance 
5 job acknowledgment 
6 output ready message. 


The optional level value of the “usr=...” field specification must be a 1- or 2-digit code of the form mw. A 
message from the host machine with importance x (where x comes from the above list) is compared with each 
digit of the two decimal digits in level. If x is greater than or equal to w and if the user is logged in and is 
accepting messages, the message will be written to the terminal of the user. Otherwise, if x is greater than or 
equal to m, the message will be mailed to the user. In all other cases, the message will be discarded. The default 
level is 54. The user should specify level 1 if it is desirable to receive complete notification and level 59 to 
divert the last two messages in the above list to the user mailbox. 


MONITORING RJE 


The RJE facility is designed to be an autonomous facility that does not require manual supervision. The 
RJE facility is initiated automatically by the UNIX operating system reboot procedures and continues in execu- 
tion until the system is shut down. Experience has shown RJE to be reasonably robust, although it is vulnerable 
to system crashes and reconfigurations. 


Users may assume that when the UNIX operating system is operating, the RJE facilities will also be avail- 
able. This implies more than an ability to execute the send(1C) command, which should be available at all times; 
it means that queued jobs should be submitted to the host machine for execution and their output returned to 
the UNIX operating system. If a user cannot obtain any throughput from the RJE facility, the user should so 
advise the UNIX administrator. 


The rjestat(1C) command, invoked with no arguments, will report the status of all RJE links for which 


a given UNIX operating system is configured. This command sometimes will also print a message of the day 
from RJE. 


$ rjestat 
RJE to B operating normally. 
RJE to A is down, reason: IBM not responding. 


A host machine may be reported not to be responding to RJE because the host machine is down. It may be 
down because the host machine operator failed to initialize the associated line. It may be down also because 
of a communications hardware failure. 


The rjestat command also has the ability to send operator commands to the host machine and to retrieve 


the responses generated by the commands. Refer to rjestat(1C) command page for a more complete description 
of this command. 
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€ TABLE 6.A 


SAMPLE JES2 OUTPUT LISTING 


& $ cat rje/prnto 


14:40:31 JOB 384 $HASP373 GENER STARTED — INIT 26 — CLASS X — SYS RRMA 
14:40:32 JOB 384 $HASP395 GENER ENDED 


—— JES2 JOB STATISTICS —— 
1 AUG 81 JOB EXECUTION DATE 
54 CARDS READ 
76 SYSOUT PRINT RECORDS 
€ 0 SYSOUT PUNCH RECORDS 
0.01 MINUTES EXECUTION TIME 
//GENER JOB (9999,R740),PGMRNAME,CLASS = X JOB 384 
*** = USR=(MYLOGIN,MYPLACE) 
//IEBGENER EXEC PGM=IEBGENER 
//8YSPRINT DD DUMMY 
//8YSIN DD DUMMY 
//SYSUT2 DD SYSOUT=A 
//SYSUT1 DD * 
// 
IEF2361_ ALLOC. FOR GENER IEBGENER 
IEF2371 DMY ALLOCATED TO SYSPRINT 
IEF2371 DMY ALLOCATED TO SYSIN 
& IEF2371 JES ALLOCATED TO SYSUT2 
IEF2371 JES ALLOCATED TO SYSUT1 
IEF142I GENER IEBGENER — STEP WAS EXECUTED — COND CODE 0000 
IEF 2851 JES2.JOB0384.500102 SYSOUT 


IEF 2851 JES2.JOB0384.S10101 SYSIN 
IEF3731 STEP /IEBGENER/ START 77242.1440 
IEF3741 STEP /IEBGENER/ STOP 7742.1440 CPU) OMIN 00.18SEC SRB  OMIN 00.01SEC VIRT 36K SYS 188K 


aes SERVICE UNITS=0000174. SERVICE RATE=0000268 SERVICE UNITS/SECOND 
eens PERFORMANCE GROUP=005 
ghivashis EXCP COUNT BY UNIT ADDRESS 
IEF3751 JOB /GENER / START 77242.1440 
& IEF3761 JOB /GENER / STOP 177242.1440 CPU) OMIN 00.18SEC SRB OMIN 00.01SEC 


sit occa SERVICE UNITS=0000174 SERVICE RATE=0000268 SERVICE UNITS/SECOND 
sake ches APPROXIMATE PROCESSING TIME= 01 MINUTES 
whisk ted EXCPS=000000000 
oreo PROJECTED CHARGES= 01 
first line of data 


e last line of data 


*OS/VS2 REL 3.7 JES2* END JOBNAME=GENER BIN=R740. JOB #=384 PGMRNAME 
*OS/VS2  REL3.7JES2* END JOBNAME=GENER BIN=R740 JOB #=384 PGMRNAME 

& *0S/VS2 REL 3.7 JES2* END JOBNAME=GENER BIN=R740 JOB 4=384 PGMRNAME 
$ rm -f rje/prnt0 
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NOTES 
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